/// @file cfgparser_prefs.h
/// @brief 偏好设置管理类，支持多种数据类型的存储和检索

#ifndef __CFGPARSER_PREFS_H__
#define __CFGPARSER_PREFS_H__

#include <map>
#include <cstring>
#include <string>
#include <type_traits>
#include <cstddef>
#include <cstdint>
#include <vector>
#include <memory>
#include <numeric>
#include <string_view>
#include <limits>
#include <mutex>
#include <shared_mutex>
#include <stdexcept>
#include <optional>

namespace cfgparser
{
    /// @brief 偏好设置管理类
    class Preferences
    {
    private:
        typedef std::vector<uint8_t> data_element_t;      // 定义数据元素结构体
        std::map<data_element_t, data_element_t> __prefs; // 用于存储键值对
        mutable std::shared_mutex __mutex;
        mutable std::size_t __state_version{0};
        mutable std::size_t __persisted_version{0};

        constexpr static std::string_view IDENTIFIER = "CFGP"; // 数据标识符

        size_t __serialize_data_size_unsafe() const
        {
            size_t data_size = sizeof(size_t); // 为map的大小保留空间
            for (const auto &pair : __prefs)
            {
                data_size += sizeof(size_t) + pair.first.size() +
                             sizeof(size_t) + pair.second.size(); // 压缩键和值的大小
            }
            return data_size;
        }

        uint16_t __serialize_unsafe(uint8_t **buffer, size_t *size) const
        {
            size_t data_size{__serialize_data_size_unsafe()};
            uint8_t *ptr = *buffer;

            size_t identifier_size = IDENTIFIER.size();

            // 写入标识符
            std::memcpy(ptr, IDENTIFIER.data(), identifier_size);
            ptr += identifier_size;

            // 写入map的大小
            size_t prefs_size = __prefs.size();
            std::memcpy(ptr, &prefs_size, sizeof(size_t));
            ptr += sizeof(size_t);

            // 用于计算校验和
            uint16_t checksum = 0;

            for (const auto &pair : __prefs)
            {
                size_t key_size = pair.first.size();
                std::memcpy(ptr, &key_size, sizeof(size_t));
                ptr += sizeof(size_t);
                std::memcpy(ptr, pair.first.data(), key_size);
                ptr += key_size;

                size_t value_size = pair.second.size();
                std::memcpy(ptr, &value_size, sizeof(size_t));
                ptr += sizeof(size_t);
                std::memcpy(ptr, pair.second.data(), value_size);
                ptr += value_size;

                // 计算校验和
                checksum ^= key_size;
                checksum ^= value_size;
                checksum ^= std::accumulate(pair.first.begin(), pair.first.end(), 0);
                checksum ^= std::accumulate(pair.second.begin(), pair.second.end(), 0);
            }

            // 写入校验和
            std::memcpy(ptr, &checksum, sizeof(checksum));
            ptr += sizeof(checksum);

            *size = identifier_size + data_size + sizeof(checksum);

            return checksum;
        }

        /// @brief 将基本类型转换为data_element_t
        /// @tparam T 基本类型
        /// @param value 基本类型的值
        /// @return 转换后的data_element_t
        template <typename T>
        data_element_t __to_data_element(T &&value)
        {
            using U = std::decay_t<T>;
            static_assert(std::is_trivially_copyable<U>::value, "Type must be trivially copyable");
            size_t length = sizeof(U);
            data_element_t element(length);
            std::memcpy(element.data(), &value, length);
            return element;
        }

        /// @brief 处理字符串类型的特化版本
        data_element_t __to_data_element(const char *value)
        {
            size_t length = std::strlen(value) + 1; // +1 包含 null 终止符
            return data_element_t(reinterpret_cast<const uint8_t *>(value),
                                  reinterpret_cast<const uint8_t *>(value) + length);
        }

        /// @brief 处理字符串类型的特化版本
        data_element_t __to_data_element(const std::string &value)
        {
            // 使用 c_str() 以包含 null 终止符
            size_t length = value.size() + 1; // +1 for '\0'
            return data_element_t(reinterpret_cast<const uint8_t *>(value.c_str()),
                                  reinterpret_cast<const uint8_t *>(value.c_str()) + length);
        }

        /// @brief 处理数组类型
        /// @tparam T 数组元素类型
        /// @param value 数组指针
        /// @param value_size 数组大小
        /// @return 转换后的data_element_t
        template <typename T>
        data_element_t __to_data_element(const T *value, size_t value_size)
        {
            if (!value || value_size == 0)
            {
                return data_element_t();
            }
            size_t length = value_size * sizeof(T);
            data_element_t element(length);
            std::memcpy(element.data(), value, length);
            return element;
        }

        /// @brief 将data_element_t转换为基本类型
        /// @tparam T 基本类型
        /// @param element data_element_t对象
        /// @return 转换后的基本类型值
        template <typename T>
        typename std::enable_if<
            std::is_trivially_copyable<T>::value &&
                !std::is_pointer<T>::value &&
                !std::is_reference<T>::value,
            T>::type
        __from_data_element(const data_element_t &element)
        {
            T value{};
            if (element.size() != sizeof(T))
            {
                return T{};
            }
            std::copy(element.begin(), element.end(), reinterpret_cast<uint8_t *>(&value));
            return value;
        }

        /// @brief 处理字符串类型的特化版本
        /// @param element data_element_t对象
        std::string __from_data_element_string(const data_element_t &element)
        {
            return std::string(reinterpret_cast<const char *>(element.data()));
        }

        /// @brief 处理数组的专门函数
        /// @param element data_element_t对象
        /// @param out_array 输出数组指针
        /// @param out_size 输出数组大小
        template <typename T>
        void __from_data_element_array(const data_element_t &element, T **out_array, size_t *out_size)
        {
            if (element.size() % sizeof(T) != 0)
            {
                *out_array = nullptr;
                *out_size = 0;
                return;
            }
            *out_size = element.size() / sizeof(T);
            *out_array = new T[*out_size];                           // 动态分配内存
            std::memcpy(*out_array, element.data(), element.size()); // 使用 memcpy 复制字节数据
        }

        /// @brief 处理数组的专门函数，返回智能指针
        /// @param element data_element_t对象
        /// @param out_size 输出数组大小
        /// @return 智能指针，自动管理内存
        template <typename T>
        std::shared_ptr<T> __from_data_element_array_shared(const data_element_t &element, size_t *out_size)
        {
            if (element.size() % sizeof(T) != 0)
            {
                if (out_size)
                {
                    *out_size = 0;
                }
                return nullptr;
            }

            *out_size = element.size() / sizeof(T);
            if (*out_size == 0)
            {
                return nullptr;
            }

            std::shared_ptr<T> ptr(new T[*out_size], std::default_delete<T[]>());
            std::memcpy(ptr.get(), element.data(), element.size());
            return ptr;
        }

        /// @brief 处理数组的专门函数，返回智能指针
        /// @param element data_element_t对象
        /// @param out_size 输出数组大小
        /// @return 智能指针，自动管理内存
        template <typename T>
        std::unique_ptr<T[]> __from_data_element_array_unique(const data_element_t &element, size_t *out_size)
        {
            if (element.size() % sizeof(T) != 0)
            {
                if (out_size)
                {
                    *out_size = 0;
                }
                return nullptr;
            }

            *out_size = element.size() / sizeof(T);
            if (*out_size == 0)
            {
                return nullptr;
            }
            std::unique_ptr<T[]> ptr(new T[*out_size]);
            std::memcpy(ptr.get(), element.data(), element.size());
            return ptr;
        }

    protected:
        struct SerializedSnapshot
        {
            std::vector<uint8_t> buffer;
            std::size_t version{0};
        };

        SerializedSnapshot __snapshot() const
        {
            std::shared_lock<std::shared_mutex> lock(__mutex);
            SerializedSnapshot snapshot;
            size_t identifier_size = IDENTIFIER.size();
            size_t buffer_size = identifier_size + __serialize_data_size_unsafe() + sizeof(uint16_t);

            snapshot.buffer.resize(buffer_size);
            uint8_t *raw_ptr = snapshot.buffer.data();
            size_t serialized_size = snapshot.buffer.size();
            __serialize_unsafe(&raw_ptr, &serialized_size);

            snapshot.buffer.resize(serialized_size);
            snapshot.version = __state_version;
            return snapshot;
        }

        bool mark_clean_if_version_matches(std::size_t version)
        {
            std::unique_lock<std::shared_mutex> lock(__mutex);
            if (__state_version == version)
            {
                __persisted_version = version;
                return true;
            }
            return false;
        }

    public:
        Preferences() {}

        virtual ~Preferences() {}

        /// @brief 获取序列化后的数据大小
        /// @return 返回序列化后的数据大小
        /// @note 不包括头标识符和校验和的大小
        inline size_t serialize_data_size() const
        {
            std::shared_lock<std::shared_mutex> lock(__mutex);
            return __serialize_data_size_unsafe();
        }

        /// @brief 将当前数据序列化为二进制数据
        /// @param buffer 输出缓冲区指针
        /// @param size 输出缓冲区大小
        /// @return 校验和
        uint16_t serialize(uint8_t **buffer, size_t *size) const
        {
            std::shared_lock<std::shared_mutex> lock(__mutex);
            return __serialize_unsafe(buffer, size);
        }

        /// @brief 将当前数据序列化为二进制数据并以vector形式返回
        /// @return 包含序列化数据的字节数组
        std::vector<uint8_t> serialize() const
        {
            return __snapshot().buffer;
        }

        /// @brief 从二进制数据加载数据
        /// @param buffer 输入缓冲区指针
        /// @param max_size 输入缓冲区最大大小
        /// @return 加载成功返回true，否则返回false
        /// @warning 需要保证buffer的大小足够容纳序列化数据，否则可能导致未定义行为
        /// @warning 如果max_size未指定，则假定缓冲区足够大
        bool deserialize(const uint8_t *buffer,
                         size_t max_size = std::numeric_limits<size_t>::max())
        {
            if (buffer == nullptr)
            {
                return false;
            }

            // 检查标识符
            size_t identifier_size = IDENTIFIER.size();

            // 检查缓冲区大小是否足够
            if (max_size < identifier_size + sizeof(size_t))
            {
                return false; // 缓冲区太小
            }

            // 检查标识符
            if (std::memcmp(buffer, IDENTIFIER.data(), identifier_size) != 0)
            {
                return false; // 标识符不匹配
            }

            const uint8_t *ptr = buffer + identifier_size;
            size_t map_size;
            std::memcpy(&map_size, ptr, sizeof(size_t));
            ptr += sizeof(size_t);

            // 检查 map_size 是否合理以及剩余的缓冲区是否足够
            if (ptr - buffer + sizeof(size_t) + map_size * (sizeof(size_t) + sizeof(size_t)) > max_size)
            {
                return false; // 数据长度超出限制
            }

            uint16_t checksum = 0;
            uint16_t calculated_checksum = 0;
            std::map<data_element_t, data_element_t> new_prefs;

            for (size_t i = 0; i < map_size; ++i)
            {
                size_t key_size;
                std::memcpy(&key_size, ptr, sizeof(size_t));
                ptr += sizeof(size_t);

                // 检查键的大小是否合理
                size_t consumed = static_cast<size_t>(ptr - buffer);
                if (consumed > max_size || key_size > max_size - consumed)
                {
                    return false; // 数据长度超出限制
                }

                data_element_t key(key_size);
                std::copy(ptr, ptr + key_size, key.begin());
                ptr += key_size;

                consumed = static_cast<size_t>(ptr - buffer);
                if (consumed > max_size || sizeof(size_t) > max_size - consumed)
                {
                    return false;
                }

                size_t value_size;
                std::memcpy(&value_size, ptr, sizeof(size_t));
                ptr += sizeof(size_t);

                // 检查值的大小是否合理
                consumed = static_cast<size_t>(ptr - buffer);
                if (consumed > max_size || value_size > max_size - consumed)
                {
                    return false; // 数据长度超出限制
                }

                data_element_t value(value_size);
                std::copy(ptr, ptr + value_size, value.begin());
                ptr += value_size;

                // 校验和计算
                calculated_checksum ^= key_size;
                calculated_checksum ^= value_size;
                calculated_checksum ^= std::accumulate(key.begin(), key.end(), 0);
                calculated_checksum ^= std::accumulate(value.begin(), value.end(), 0);

                new_prefs[std::move(key)] = std::move(value);
            }

            // 读取校验和
            if (ptr - buffer + sizeof(checksum) > max_size)
            {
                return false; // 数据长度超出限制
            }
            std::memcpy(&checksum, ptr, sizeof(checksum));

            // 比较校验和
            if (checksum != calculated_checksum)
            {
                return false; // 校验和不匹配，表示数据错误
            }

            {
                std::unique_lock<std::shared_mutex> lock(__mutex);
                __prefs = std::move(new_prefs);
                ++__state_version;
                __persisted_version = __state_version;
            }

            return true;
        }

        /// @brief 设置指定键的值（普通类型）
        /// @tparam KEY_T 键类型
        /// @tparam VALUE_T 值类型
        /// @param key 键
        /// @param value 值
        /// @return 当前对象引用，便于链式调用
        template <typename KEY_T, typename VALUE_T,
                  typename = std::enable_if_t<std::is_trivially_copyable<std::decay_t<VALUE_T>>::value>>
        Preferences &set(KEY_T &&key, VALUE_T &&value)
        {
            // 将键转换为data_element_t
            data_element_t keyElement = __to_data_element(std::forward<KEY_T>(key));
            data_element_t valueElement = __to_data_element(std::forward<VALUE_T>(value));

            // 更新map中的值
            std::unique_lock<std::shared_mutex> lock(__mutex);
            __prefs[std::move(keyElement)] = std::move(valueElement);
            ++__state_version;

            return *this;
        }

        template <typename KEY_T, typename VALUE_T,
                  typename = std::enable_if_t<std::is_trivially_copyable<std::decay_t<VALUE_T>>::value>>
        Preferences &set_if_not_equal(KEY_T &&key, VALUE_T &&value)
        {
            // 将键转换为data_element_t
            data_element_t keyElement = __to_data_element(std::forward<KEY_T>(key));
            data_element_t valueElement = __to_data_element(std::forward<VALUE_T>(value));

            // 更新map中的值
            std::unique_lock<std::shared_mutex> lock(__mutex);
            // 如果数据没有变化
            if ((__prefs.find(keyElement) != __prefs.end()) &&
                (valueElement == __prefs[keyElement]))
            {
                return *this;
            }
            // 如果数据有变化
            __prefs[std::move(keyElement)] = std::move(valueElement);
            ++__state_version;

            return *this;
        }

        /// @brief 设置指定键的值（数组类型）
        /// @tparam KEY_T 键类型
        /// @tparam VALUE_T 值类型
        /// @param key 键
        /// @param value 值
        /// @param value_size 值的大小
        /// @return 当前对象引用，便于链式调用
        template <typename KEY_T, typename VALUE_T>
        Preferences &set(KEY_T &&key, VALUE_T *value, size_t value_size)
        {
            // 将键转换为data_element_t
            data_element_t keyElement = __to_data_element(std::forward<KEY_T>(key));
            data_element_t valueElement = __to_data_element(value, value_size);

            // 更新map中的值
            std::unique_lock<std::shared_mutex> lock(__mutex);
            __prefs[std::move(keyElement)] = std::move(valueElement);
            ++__state_version;

            return *this;
        }

        template <typename KEY_T, typename VALUE_T>
        Preferences &set_if_not_equal(KEY_T &&key, VALUE_T *value, size_t value_size)
        {
            // 将键转换为data_element_t
            data_element_t keyElement = __to_data_element(std::forward<KEY_T>(key));
            data_element_t valueElement = __to_data_element(value, value_size);

            // 更新map中的值
            std::unique_lock<std::shared_mutex> lock(__mutex);
            // 如果数据没有变化
            if ((__prefs.find(keyElement) != __prefs.end()) &&
                (valueElement == __prefs[keyElement]))
            {
                return *this;
            }
            // 如果数据有变化
            __prefs[std::move(keyElement)] = std::move(valueElement);
            ++__state_version;

            return *this;
        }

        /// @brief 设置指定键的值（std::string类型）
        /// @tparam KEY_T 键类型
        /// @param key 键
        /// @param value 值
        /// @return 当前对象引用，便于链式调用
        template <typename KEY_T>
        Preferences &set(KEY_T &&key, const std::string &value)
        {
            data_element_t keyElement = __to_data_element(std::forward<KEY_T>(key));
            data_element_t valueElement = __to_data_element(value);

            std::unique_lock<std::shared_mutex> lock(__mutex);
            __prefs[std::move(keyElement)] = std::move(valueElement);
            ++__state_version;

            return *this;
        }

        template <typename KEY_T>
        Preferences &set_if_not_equal(KEY_T &&key, const std::string &value)
        {
            data_element_t keyElement = __to_data_element(std::forward<KEY_T>(key));
            data_element_t valueElement = __to_data_element(value);

            std::unique_lock<std::shared_mutex> lock(__mutex);
            // 如果数据没有变化
            if ((__prefs.find(keyElement) != __prefs.end()) &&
                (valueElement == __prefs[keyElement]))
            {
                return *this;
            }
            // 如果数据有变化
            __prefs[std::move(keyElement)] = std::move(valueElement);
            ++__state_version;

            return *this;
        }

        /// @brief 设置指定键的值（std::vector类型）
        /// @tparam KEY_T 键类型
        /// @tparam VALUE_T 值类型
        /// @param key 键
        /// @param value 值
        /// @param value_size 值的大小
        /// @return 当前对象引用，便于链式调用
        template <typename KEY_T, typename VALUE_T>
        Preferences &set(KEY_T &&key, const std::vector<VALUE_T> &value)
        {
            // 将键转换为data_element_t
            data_element_t keyElement = __to_data_element(std::forward<KEY_T>(key));
            data_element_t valueElement = __to_data_element(value.data(), value.size());

            // 更新map中的值
            std::unique_lock<std::shared_mutex> lock(__mutex);
            __prefs[std::move(keyElement)] = std::move(valueElement);
            ++__state_version;

            return *this;
        }

        template <typename KEY_T, typename VALUE_T>
        Preferences &set_if_not_equal(KEY_T &&key, const std::vector<VALUE_T> &value)
        {
            // 将键转换为data_element_t
            data_element_t keyElement = __to_data_element(std::forward<KEY_T>(key));
            data_element_t valueElement = __to_data_element(value.data(), value.size());

            // 更新map中的值
            std::unique_lock<std::shared_mutex> lock(__mutex);
            // 如果数据没有变化
            if ((__prefs.find(keyElement) != __prefs.end()) &&
                (valueElement == __prefs[keyElement]))
            {
                return *this;
            }
            // 如果数据有变化
            __prefs[std::move(keyElement)] = std::move(valueElement);
            ++__state_version;

            return *this;
        }

        /// @brief 设置指定键的值（std::shared_ptr<T[]>数组类型）
        /// @tparam KEY_T 键类型
        /// @tparam VALUE_T 数组元素类型
        /// @param key 键
        /// @param value shared_ptr 数组
        /// @param array_size 数组元素个数
        /// @return 当前对象引用，便于链式调用
        template <typename KEY_T, typename VALUE_T>
        Preferences &set(KEY_T &&key, std::shared_ptr<VALUE_T[]> value, size_t array_size)
        {
            data_element_t keyElement = __to_data_element(std::forward<KEY_T>(key));
            std::unique_lock<std::shared_mutex> lock(__mutex);
            if (!value || array_size == 0)
            {
                if (__prefs.erase(keyElement) > 0)
                {
                    ++__state_version;
                }
                return *this;
            }

            data_element_t valueElement = __to_data_element(value.get(), array_size);

            __prefs[std::move(keyElement)] = std::move(valueElement);
            ++__state_version;

            return *this;
        }

        template <typename KEY_T, typename VALUE_T>
        Preferences &set_if_not_equal(KEY_T &&key, std::shared_ptr<VALUE_T[]> value, size_t array_size)
        {
            data_element_t keyElement = __to_data_element(std::forward<KEY_T>(key));
            std::unique_lock<std::shared_mutex> lock(__mutex);
            if (!value || array_size == 0)
            {
                if (__prefs.erase(keyElement) > 0)
                {
                    ++__state_version;
                }
                return *this;
            }

            data_element_t valueElement = __to_data_element(value.get(), array_size);
            // 如果数据没有变化
            if ((__prefs.find(keyElement) != __prefs.end()) &&
                (valueElement == __prefs[keyElement]))
            {
                return *this;
            }
            // 如果数据有变化
            __prefs[std::move(keyElement)] = std::move(valueElement);
            ++__state_version;

            return *this;
        }

        /// @brief 设置指定键的值（std::shared_ptr<std::vector>类型）
        /// @tparam KEY_T 键类型
        /// @tparam VALUE_T vector元素类型
        /// @param key 键
        /// @param value shared_ptr 指向的 vector
        /// @return 当前对象引用，便于链式调用
        template <typename KEY_T, typename VALUE_T>
        Preferences &set(KEY_T &&key, std::shared_ptr<std::vector<VALUE_T>> value)
        {
            data_element_t keyElement = __to_data_element(std::forward<KEY_T>(key));
            std::unique_lock<std::shared_mutex> lock(__mutex);
            if (!value || value->empty())
            {
                if (__prefs.erase(keyElement) > 0)
                {
                    ++__state_version;
                }
                return *this;
            }

            data_element_t valueElement = __to_data_element(value->data(), value->size());

            __prefs[std::move(keyElement)] = std::move(valueElement);
            ++__state_version;

            return *this;
        }

        template <typename KEY_T, typename VALUE_T>
        Preferences &set_if_not_equal(KEY_T &&key, std::shared_ptr<std::vector<VALUE_T>> value)
        {
            data_element_t keyElement = __to_data_element(std::forward<KEY_T>(key));
            std::unique_lock<std::shared_mutex> lock(__mutex);
            if (!value || value->empty())
            {
                if (__prefs.erase(keyElement) > 0)
                {
                    ++__state_version;
                }
                return *this;
            }

            data_element_t valueElement = __to_data_element(value->data(), value->size());

            // 如果数据没有变化
            if ((__prefs.find(keyElement) != __prefs.end()) &&
                (valueElement == __prefs[keyElement]))
            {
                return *this;
            }
            // 如果数据有变化
            __prefs[std::move(keyElement)] = std::move(valueElement);
            ++__state_version;

            return *this;
        }

        /// @brief 仅当指定键不存在时设置其值
        /// @tparam KEY_T 键类型
        /// @tparam ARGS_T 可变参数模板
        /// @param key 键
        /// @param args 传递给 Preferences::set 的参数
        /// @return 当前对象引用，便于链式调用
        template <typename KEY_T, typename... ARGS_T>
        Preferences &set_if_no_key(KEY_T &&key, ARGS_T &&...args)
        {
            if constexpr (sizeof...(args) == 0)
            {
                return *this;
            }
            if (!contains(std::forward<KEY_T>(key)))
            {
                return set(std::forward<KEY_T>(key), std::forward<ARGS_T>(args)...);
            }
            return *this;
        }

        /// @brief 获取指定键的值（std::string）
        /// @tparam KEY_T 键类型
        /// @param key 键
        /// @param default_value 默认值
        /// @return 值或默认值
        template <typename KEY_T>
        std::string get(KEY_T &&key, const std::string &default_value)
        {
            data_element_t keyElement = __to_data_element(std::forward<KEY_T>(key));
            std::shared_lock<std::shared_mutex> lock(__mutex);
            auto it = __prefs.find(keyElement);
            if (it != __prefs.end())
            {
                return __from_data_element_string(it->second); // 对std::string的特殊处理
            }
            return default_value;
        }

        /// @brief 获取指定键的值（std::string），无默认值版本，找不到返回 std::nullopt
        /// @param key 键
        template <typename KEY_T>
        std::optional<std::string> get(KEY_T &&key)
        {
            data_element_t keyElement = __to_data_element(std::forward<KEY_T>(key));
            std::shared_lock<std::shared_mutex> lock(__mutex);
            auto it = __prefs.find(keyElement);
            if (it != __prefs.end())
            {
                return __from_data_element_string(it->second);
            }
            return std::nullopt;
        }

        /// @brief 获取指定键的值（普通类型）
        /// @tparam KEY_T 键类型
        /// @tparam VALUE_T 值类型
        /// @param key 键
        /// @param default_value 默认值
        /// @return 值或默认值
        template <typename KEY_T, typename VALUE_T,
                  typename = std::enable_if_t<std::is_trivially_copyable<std::decay_t<VALUE_T>>::value>>
        std::decay_t<VALUE_T> get(KEY_T &&key, VALUE_T &&default_value)
        {
            data_element_t keyElement = __to_data_element(std::forward<KEY_T>(key));
            std::shared_lock<std::shared_mutex> lock(__mutex);
            auto it = __prefs.find(keyElement);
            if (it != __prefs.end())
            {
                return __from_data_element<std::decay_t<VALUE_T>>(it->second);
            }
            return default_value;
        }

        /// @brief 获取指定键的值（普通类型），无默认值版本，找不到返回 std::nullopt
        /// @param key 键
        template <typename KEY_T, typename VALUE_T,
                  typename = std::enable_if_t<std::is_trivially_copyable<std::decay_t<VALUE_T>>::value>>
        std::optional<std::decay_t<VALUE_T>> get(KEY_T &&key)
        {
            data_element_t keyElement = __to_data_element(std::forward<KEY_T>(key));
            std::shared_lock<std::shared_mutex> lock(__mutex);
            auto it = __prefs.find(keyElement);
            if (it != __prefs.end())
            {
                return __from_data_element<std::decay_t<VALUE_T>>(it->second);
            }
            return std::nullopt;
        }

        /// @brief 获取指定键的值（数组类型）
        /// @tparam KEY_T 键类型
        /// @tparam VALUE_T 值类型
        /// @param key 键
        /// @param out_array 输出数组指针
        /// @param out_size 输出数组大小
        /// @note out_array为数组指针或nullptr
        /// @note out_array如果不为nullptr，则需要手动释放内存
        template <typename KEY_T, typename VALUE_T>
        void get(KEY_T &&key, VALUE_T **out_array, size_t *out_size)
        {
            data_element_t keyElement = __to_data_element(std::forward<KEY_T>(key));
            std::shared_lock<std::shared_mutex> lock(__mutex);
            auto it = __prefs.find(keyElement);
            if (it != __prefs.end())
            {
                __from_data_element_array(it->second, out_array, out_size); // 从data_element_t中提取数组
                return;
            }

            *out_array = nullptr;
            *out_size = 0; // 如果未找到，则设置大小为0
        }

        /// @brief 获取指定键的值（数组类型），无默认值版本，返回 std::optional<std::vector<T>>，找不到或格式不对返回 std::nullopt
        /// @param key 键
        template <typename KEY_T, typename VALUE_T>
        std::optional<std::vector<VALUE_T>> get(KEY_T &&key)
        {
            data_element_t keyElement = __to_data_element(std::forward<KEY_T>(key));
            std::shared_lock<std::shared_mutex> lock(__mutex);
            auto it = __prefs.find(keyElement);
            if (it == __prefs.end())
            {
                return std::nullopt;
            }

            if (it->second.size() % sizeof(VALUE_T) != 0)
            {
                return std::nullopt;
            }

            std::vector<VALUE_T> out_array(it->second.size() / sizeof(VALUE_T));
            std::memcpy(out_array.data(), it->second.data(), it->second.size());
            return out_array;
        }

        /// @brief 获取指定键的值（std::shared_ptr数组）
        /// @tparam KEY_T 键类型
        /// @tparam VALUE_T 值类型
        /// @param key 键
        /// @param out_size 输出数组大小，可为空
        /// @return 指向数组的std::shared_ptr
        template <typename KEY_T, typename VALUE_T>
        std::shared_ptr<VALUE_T> get_shared(KEY_T &&key, size_t *out_size = nullptr)
        {
            data_element_t keyElement = __to_data_element(std::forward<KEY_T>(key));
            std::shared_lock<std::shared_mutex> lock(__mutex);
            auto it = __prefs.find(keyElement);
            if (it == __prefs.end())
            {
                if (out_size)
                {
                    *out_size = 0;
                }
                return nullptr;
            }

            size_t local_size = 0;
            size_t *size_ptr = out_size ? out_size : &local_size;
            auto result = __from_data_element_array_shared<VALUE_T>(it->second, size_ptr);
            if (!result && out_size)
            {
                *out_size = 0;
            }
            return result;
        }

        /// @brief 获取指定键的值（std::unique_ptr数组）
        /// @tparam KEY_T 键类型
        /// @tparam VALUE_T 值类型
        /// @param key 键
        /// @param out_size 输出数组大小，可为空
        /// @return 指向数组的std::unique_ptr
        template <typename KEY_T, typename VALUE_T>
        std::unique_ptr<VALUE_T[]> get_unique(KEY_T &&key, size_t *out_size = nullptr)
        {
            data_element_t keyElement = __to_data_element(std::forward<KEY_T>(key));
            std::shared_lock<std::shared_mutex> lock(__mutex);
            auto it = __prefs.find(keyElement);
            if (it == __prefs.end())
            {
                if (out_size)
                {
                    *out_size = 0;
                }
                return nullptr;
            }

            size_t local_size = 0;
            size_t *size_ptr = out_size ? out_size : &local_size;
            auto result = __from_data_element_array_unique<VALUE_T>(it->second, size_ptr);
            if (!result && out_size)
            {
                *out_size = 0;
            }
            return result;
        }

        /// @brief 获取指定键的值（std::vector）
        /// @tparam KEY_T 键类型
        /// @tparam VALUE_T 值类型
        /// @param key 键
        /// @param default_array 默认数组
        /// @return 返回std::vector对象
        /// @note out_array为std::vector对象
        template <typename KEY_T, typename VALUE_T>
        std::vector<VALUE_T> get(KEY_T &&key, std::vector<VALUE_T> default_array)
        {
            data_element_t keyElement = __to_data_element(std::forward<KEY_T>(key));
            std::shared_lock<std::shared_mutex> lock(__mutex);
            auto it = __prefs.find(keyElement);
            if (it == __prefs.end())
            {
                return default_array;
            }

            // 检查数据大小是否合理
            if (it->second.size() % sizeof(VALUE_T) != 0)
            {
                return default_array;
            }

            std::vector<VALUE_T> out_array(it->second.size() / sizeof(VALUE_T));
            std::memcpy(out_array.data(), it->second.data(), it->second.size());
            return out_array;
        }

        // --- 便捷非模板封装（常用类型） ---
        /// @brief 便捷获取 int 类型（无默认），返回 std::optional<int>
        /// @param key 键
        template <typename KEY_T>
        std::optional<int> get_int(KEY_T &&key)
        {
            return get<KEY_T, int>(std::forward<KEY_T>(key));
        }

        /// @brief 便捷获取 std::string 类型（无默认），返回 std::optional<std::string>
        /// @param key 键
        template <typename KEY_T>
        std::optional<std::string> get_string(KEY_T &&key)
        {
            return get(std::forward<KEY_T>(key));
        }

        /// @brief 便捷获取 vector<T> 类型（无默认），返回 std::optional<std::vector<T>>
        /// @param key 键
        template <typename KEY_T, typename VALUE_T>
        std::optional<std::vector<VALUE_T>> get_vector(KEY_T &&key)
        {
            return get<KEY_T, VALUE_T>(std::forward<KEY_T>(key));
        }

        /// @brief 便捷获取 bool 类型（无默认），返回 std::optional<bool>
        /// @param key 键
        template <typename KEY_T>
        std::optional<bool> get_bool(KEY_T &&key)
        {
            return get<KEY_T, bool>(std::forward<KEY_T>(key));
        }

        /// @brief 便捷获取 float 类型（无默认），返回 std::optional<float>
        template <typename KEY_T>
        std::optional<float> get_float(KEY_T &&key)
        {
            return get<KEY_T, float>(std::forward<KEY_T>(key));
        }

        /// @brief 便捷获取 double 类型（无默认），返回 std::optional<double>
        /// @param key 键
        template <typename KEY_T>
        std::optional<double> get_double(KEY_T &&key)
        {
            return get<KEY_T, double>(std::forward<KEY_T>(key));
        }

        /// @brief 便捷获取 long 类型（无默认），返回 std::optional<long>
        /// @param key 键
        template <typename KEY_T>
        std::optional<long> get_long(KEY_T &&key)
        {
            return get<KEY_T, long>(std::forward<KEY_T>(key));
        }

        /// @brief 便捷获取 uint32_t 类型（无默认），返回 std::optional<uint32_t>
        /// @param key 键
        template <typename KEY_T>
        std::optional<uint32_t> get_uint32(KEY_T &&key)
        {
            return get<KEY_T, uint32_t>(std::forward<KEY_T>(key));
        }

        /// @brief 便捷获取 size_t 类型（无默认），返回 std::optional<size_t>
        /// @param key 键
        template <typename KEY_T>
        std::optional<size_t> get_size_t(KEY_T &&key)
        {
            return get<KEY_T, size_t>(std::forward<KEY_T>(key));
        }

        /// @brief 便捷获取 uint64_t 类型（无默认），返回 std::optional<uint64_t>
        /// @param key 键
        template <typename KEY_T>
        std::optional<uint64_t> get_uint64(KEY_T &&key)
        {
            return get<KEY_T, uint64_t>(std::forward<KEY_T>(key));
        }

        /// @brief 便捷获取 uint16_t 类型（无默认），返回 std::optional<uint16_t>
        /// @param key 键
        template <typename KEY_T>
        std::optional<uint16_t> get_uint16(KEY_T &&key)
        {
            return get<KEY_T, uint16_t>(std::forward<KEY_T>(key));
        }

        /// @brief 便捷获取 unsigned long long 类型（无默认），返回 std::optional<unsigned long long>
        /// @param key 键
        template <typename KEY_T>
        std::optional<unsigned long long> get_ulonglong(KEY_T &&key)
        {
            return get<KEY_T, unsigned long long>(std::forward<KEY_T>(key));
        }

        /// @brief 获取指定键的值（std::shared_ptr）
        /// @tparam KEY_T 键类型
        /// @tparam VALUE_T 值类型
        /// @param key 键
        /// @param default_array 默认数组
        /// @return 返回std::shared_ptr对象
        /// @note out_array为std::shared_ptr对象，VALUE_T 必须是数组元素类型，而非数组本身
        template <typename KEY_T, typename VALUE_T>
        std::shared_ptr<VALUE_T[]> get(KEY_T &&key, std::shared_ptr<VALUE_T[]> default_array)
        {
            data_element_t keyElement = __to_data_element(std::forward<KEY_T>(key));
            std::shared_lock<std::shared_mutex> lock(__mutex);
            auto it = __prefs.find(keyElement);
            if (it == __prefs.end())
            {
                return default_array;
            }

            // 检查数据大小是否合理
            if (it->second.size() % sizeof(VALUE_T) != 0)
            {
                return default_array;
            }

            size_t array_size = it->second.size() / sizeof(VALUE_T);
            std::shared_ptr<VALUE_T[]> out_array(new VALUE_T[array_size]);
            std::memcpy(out_array.get(), it->second.data(), it->second.size());
            return out_array;
        }

        /// @brief 删除指定键的值
        /// @tparam KEY_T 键类型
        /// @param key 键
        template <typename KEY_T>
        void remove(KEY_T &&key)
        {
            data_element_t keyElement = __to_data_element(std::forward<KEY_T>(key));
            std::unique_lock<std::shared_mutex> lock(__mutex);
            if (__prefs.erase(keyElement) > 0)
            {
                ++__state_version;
            }
        }

        /// @brief 清空所有键值对
        void clear()
        {
            std::unique_lock<std::shared_mutex> lock(__mutex);
            if (!__prefs.empty())
            {
                __prefs.clear(); // std::vector会自动管理内存，因此无需手动释放
                ++__state_version;
            }
        }

        /// @brief 检查指定键是否存在
        /// @tparam KEY_T 键类型
        /// @param key 键
        /// @return 是否存在
        template <typename KEY_T>
        bool contains(KEY_T &&key)
        {
            data_element_t keyElement = __to_data_element(std::forward<KEY_T>(key));
            std::shared_lock<std::shared_mutex> lock(__mutex);
            return __prefs.find(keyElement) != __prefs.end();
        }

        /// @brief 数据是否已修改
        /// @return 如果存在未持久化的修改则返回true
        bool is_dirty() const
        {
            std::shared_lock<std::shared_mutex> lock(__mutex);
            return __state_version != __persisted_version;
        }

        /// @brief 标记当前数据为干净状态（兼容旧接口，尽量避免在多线程上下文直接调用）
        void mark_clean()
        {
            std::unique_lock<std::shared_mutex> lock(__mutex);
            __persisted_version = __state_version;
        }

        /// @brief 重载[]运算符，获取指定键的值
        /// @tparam KEY_T 键类型
        /// @tparam VALUE_T 值类型
        /// @param key 键
        template <typename KEY_T, typename VALUE_T>
        VALUE_T &operator[](KEY_T &&key)
        {
            using value_type = std::decay_t<VALUE_T>;
            static_assert(std::is_trivially_copyable<value_type>::value ||
                              std::is_same_v<value_type, std::string>,
                          "operator[] only supports trivially copyable types or std::string");

            data_element_t key_element = __to_data_element(std::forward<KEY_T>(key));

            std::shared_lock<std::shared_mutex> lock(__mutex);
            auto it = __prefs.find(key_element);
            if (it == __prefs.end())
            {
                throw std::out_of_range("Preference key not found");
            }

            const data_element_t &raw = it->second;

            if constexpr (std::is_same_v<value_type, std::string>)
            {
                if (raw.empty() || raw.back() != '\0')
                {
                    throw std::runtime_error("Stored value is not a valid null-terminated string");
                }

                thread_local std::string storage;
                storage.assign(reinterpret_cast<const char *>(raw.data()));
                return reinterpret_cast<VALUE_T &>(storage);
            }
            else
            {
                if (raw.size() != sizeof(value_type))
                {
                    throw std::runtime_error("Stored value size does not match requested type");
                }

                thread_local std::aligned_storage_t<sizeof(value_type), alignof(value_type)> storage;
                value_type *value_ptr = reinterpret_cast<value_type *>(&storage);
                std::memcpy(value_ptr, raw.data(), sizeof(value_type));
                return reinterpret_cast<VALUE_T &>(*value_ptr);
            }
        }

        /// @brief 枚举当前存储的所有键值对（以原始字节返回）
        /// @return 包含键、值字节向量的列表
        std::vector<std::pair<data_element_t, data_element_t>> enumerate() const
        {
            std::shared_lock<std::shared_mutex> lock(__mutex);
            std::vector<std::pair<data_element_t, data_element_t>> entries;
            entries.reserve(__prefs.size());
            for (const auto &kv : __prefs)
            {
                entries.emplace_back(kv.first, kv.second);
            }
            return entries;
        }
    };
} // namespace cfgparser

#endif // __CFGPARSER_PREFS_H__
